package me.flyray.bsin.facade.engine;

import com.baomidou.mybatisplus.core.metadata.IPage;
import me.flyray.bsin.domain.entity.CustomerPassCard;
import me.flyray.bsin.domain.entity.DigitalAssetsCollection;
import me.flyray.bsin.facade.response.DigitalAssetsDetailRes;
import me.flyray.bsin.facade.response.DigitalAssetsItemRes;
import me.flyray.bsin.facade.response.PassCardVo;

import java.util.List;
import java.util.Map;

/**
 * PassCard品牌会员卡服务引擎接口
 * 
 * 功能概述：
 * 基于DID身份档案的品牌会员卡管理系统，是整个身份体系的会员层
 * 
 * 架构关系：
 * - 基础层：DID（去中心化身份标识）
 * - 档案层：Profile（身份档案）1:1 映射DID
 * - 会员层：PassCard（本接口管理的品牌会员卡）1:N 关联Profile
 * - 应用层：Wallet（ERC6551 TBA钱包）、Agent（AI数字分身）
 * 
 * 核心概念：
 * - PassCard：基于Profile的品牌会员卡，每张卡都是独特的NFT资产
 * - TBA钱包：每张PassCard自动生成独立的ERC6551钱包地址
 * - 卡号规则：{DID标识符}_{NFT编号}，确保全局唯一性
 * - 多品牌支持：一个Profile可以开通多个品牌的会员卡
 * 
 * 业务流程：
 * 1. 前置条件：用户已有DID身份和Profile档案
 * 2. 商户发行PassCard集合（issue方法）
 * 3. 用户申请开卡（claim方法）
 * 4. 系统自动生成：NFT会员卡 + TBA钱包 + 唯一卡号
 * 5. 激活会员权益和Agent数字分身能力
 * 
 * 技术特点：
 * - 基于ERC6551的TBA（Token Bound Account）技术
 * - 每个会员卡都是独特的NFT资产，可交易可继承
 * - 支持跨品牌的会员权益互通
 * - 与DID身份体系深度集成，确保安全性
 * 
 * @author bolei
 * @date 2023/6/27 19:46
 * @desc PassCard品牌会员卡服务引擎 - 身份体系的会员层
 */

public interface PassCardServiceEngine {

    /**
     * 品牌商户发行Pass Card
     * 
     * 功能说明：
     * - 品牌商户创建数字资产集合（DigitalAssetsCollection）
     * - 设置NFT元数据、属性、稀有度等
     * - 配置开卡规则和权限
     * - 上架到数字资产市场
     * 
     * 技术实现：
     * - 创建智能合约（如果使用区块链）
     * - 设置NFT集合的元数据URI
     * - 配置铸造权限和规则
     * - 关联DID身份验证
     * 
     * @param requestMap 发行参数，包含品牌信息、NFT配置、开卡规则等
     * @throws Exception 发行过程中的异常
     */
    public DigitalAssetsCollection issue(Map<String, Object> requestMap) throws Exception;

    /**
     * 用户开通品牌会员卡
     * 
     * 功能说明：
     * - 基于已有的DID身份和Profile档案开通品牌会员卡
     * - 自动铸造NFT会员卡并生成TBA钱包地址
     * - 建立用户与品牌之间的会员关系
     * 
     * 前置条件：
     * 1. 用户必须已有DID身份（通过DidProfileServiceEngine.create创建）
     * 2. 用户必须已有Profile档案
     * 3. 商户必须已发行PassCard集合（通过issue方法）
     * 
     * 开卡流程：
     * 1. 验证DID身份和Profile档案的有效性
     * 2. 检查用户是否已在该商户开卡（避免重复开卡）
     * 3. 铸造NFT会员卡（基于DigitalAssetsCollection）
     * 4. 生成ERC6551 TBA钱包地址（与NFT绑定）
     * 5. 生成唯一卡号：{DID标识符}_{NFT编号}
     * 6. 保存PassCard会员关系到数据库
     * 7. 激活会员权益和Agent数字分身能力
     * 
     * 数据关联：
     * - PassCard.tenantId -> 租户ID
     * - PassCard.customerNo -> 客户编号（关联Profile）
     * - PassCard.tokenId -> NFT代币ID
     * - PassCard.merchantNo -> 商户编号
     * - PassCard.tbaAddress -> ERC6551 TBA钱包地址
     * - PassCard.digitalAssetsItemNo -> 数字资产编号
     * 
     * 后续能力：
     * - TBA钱包：支持数字资产存储、转账、DeFi交互
     * - Agent数字分身：基于PassCard身份的AI服务
     * - 权益管理：会员折扣、积分、专属服务等
     * 
     * @param requestMap 开卡请求参数，包含：
     *                  - customerNo: 客户编号
     *                  - merchantNo: 商户编号  
     *                  - tenantId: 租户ID
     * @return PassCardVo 开卡结果，包含：
     *                    - cardNo: 生成的卡号
     *                    - tbaAddress: TBA钱包地址
     *                    - tokenId: NFT代币ID
     *                    - 其他会员卡信息
     * @throws Exception 开卡过程中的异常（DID不存在、重复开卡等）
     */
    public PassCardVo claim(Map<String, Object> requestMap) throws Exception;

    /**
     * 分页查询PassCard会员卡列表
     * 
     * 功能说明：
     * - 分页查询租户或商户下的所有PassCard
     * - 支持多维度筛选和排序
     * - 用于会员卡的统计和管理
     * 
     * 查询维度：
     * - 按租户ID查询：查看租户下所有会员卡
     * - 按商户ID查询：查看特定品牌的会员卡
     * - 按状态筛选：活跃、冻结、过期等状态
     * - 按时间排序：开卡时间、最后活跃时间等
     * 
     * @param requestMap 查询参数，包含分页信息和筛选条件
     * @return IPage<?> 分页查询结果
     */
    public IPage<?> getPageList(Map<String, Object> requestMap);

    /**
     * 查询商户的会员列表
     * 
     * 功能说明：
     * - 查询指定品牌商户的所有会员
     * - 显示会员的DID、NFT、开卡时间等信息
     * - 支持分页和条件筛选
     * 
     * 数据来源：
     * - 基于CustomerPassCard表查询
     * - 关联用户信息和DID数据
     * - 按商户ID筛选
     * 
     * @param requestMap 查询参数，包含商户ID、分页参数、筛选条件等
     * @return List<?> 会员列表，具体类型根据业务需求确定
     */
    public List<?> getMemberList(Map<String, Object> requestMap);

    /**
     * 查询商户发行的Pass Card数字资产集合
     * 
     * 功能说明：
     * - 查询指定商户创建的数字资产集合
     * - 显示NFT集合的元数据、属性、配置等信息
     * - 包含铸造规则、权限设置等
     * 
     * 技术实现：
     * - 基于DigitalAssetsCollection表查询
     * - 关联智能合约信息（如果使用区块链）
     * - 包含NFT元数据URI和配置
     * 
     * @param requestMap 查询参数，包含商户ID等
     * @return DigitalAssetsCollection 数字资产集合信息
     */
    public List<DigitalAssetsItemRes> getMerchantPaasCardList(Map<String, Object> requestMap);

    /**
     * 查询用户在指定商户下的通行证详情
     * 
     * 功能说明：
     * - 检查用户是否在指定商户下已开通会员卡
     * - 返回用户的DID、NFT、卡号等详细信息
     * - 用于权限验证和状态检查
     * 
     * 业务场景：
     * - 用户访问商户服务时的身份验证
     * - 检查会员权益和权限
     * - 显示用户的会员卡状态
     * 
     * 数据关联：
     * - 基于用户ID + 商户ID查询
     * - 关联DID和NFT信息
     * - 返回完整的数字资产详情
     * 
     * @param requestMap 查询参数，包含用户ID、商户ID等
     * @return DigitalAssetsDetailRes 数字资产详情，如果未开卡则返回null
     */
    public DigitalAssetsDetailRes getCustomerPaasCardByMerchantNo(Map<String, Object> requestMap);

}
